IconMethodToRgn

IconMethodToRgn
Header:	Icons.h		Carbon status:	Supported

Converts, to a region, the mask for an icon that IconMethodToRgn obtains with the aid of your icon getter callback function.

OSErr IconMethodToRgn (
     theRgn, 
    const Rect *iconRect, 
    IconAlignmentType align, 
    IconGetterUPP theMethod, 
    void *yourDataPtr
);

theRgn

On return, a handle to the requested region. You must allocate memory for the region handle before calling this function.

Once you have a region that describes the icon mask for a given icon, you can use it to perform accurate hit-testing and outline dragging of the icon in your application.

iconRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The function obtains the data for the icon mask from your icon getter function and then converts the icon mask to a region. The function uses the rectangle specified in this parameter as the bounding box of the region.

align

Specifies how the function should align the mask within the rectangle. See “Alignment Type Values” for a description of the values you can use in this parameter.

theMethod

A universal procedure pointer to your icon getter callback function. IconMethodToRgn passes to your icon getter function the type of the icon to get and the value specified in the yourDataPtr parameter. The IconMethodToRgn function examines the size of the rectangle and requests the appropriate icon from your icon getter function—an icon of icon type 'ICN#' or 'ics#'. Your icon getter function should return a handle to the data of the requested icon type. The IconMethodToRgn function extracts the mask from the icon data that your icon getter function returns. If your icon getter function returns data that does not correspond to an icon of type 'ICN#' or type 'ics#', IconMethodToRgn attempts to generate a mask from the returned data.

Your icon getter function can get the data for the icon and its mask using whatever method is appropriate to your application. For example, your application might maintain its own cache of icons (and pass a pointer to it in the yourDataPtr parameter) or use its icon getter function to get an icon from the desktop database.

See the IconGetterProcPtr callback for more information on creating an icon getter function.

yourDataPtr

function result: A result code.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.